home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / p_man / cat3 / SLGetQueue.z / SLGetQueue
Text File  |  1998-10-30  |  10KB  |  199 lines
  1.  
  2.  
  3.  
  4. SSSSLLLLGGGGeeeettttQQQQuuuueeeeuuuueeee((((3333))))                    IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                     SSSSLLLLGGGGeeeettttQQQQuuuueeeeuuuueeee((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      SLGetQueue - reports the printer queue contents
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ssssppppoooooooollll....hhhh>>>>
  13.  
  14.      iiiinnnntttt SSSSLLLLGGGGeeeettttQQQQuuuueeeeuuuueeee((((ccccoooonnnnsssstttt SSSSLLLLPPPPrrrriiiinnnntttteeeerrrrSSSSttttrrrruuuucccctttt ****pppprrrriiiinnnntttteeeerrrr____iiiinnnnffffoooo,,,,
  15.                     iiiinnnntttt qqqquuuueeeeuuuueeee____ttttyyyyppppeeee,,,,
  16.                     SSSSLLLLQQQQuuuueeeeuuuueeeeSSSSttttrrrruuuucccctttt ****qqqquuuueeeeuuuueeeepppp[[[[]]]],,,,
  17.                     iiiinnnntttt ****nnnnuuuummmm____qqqquuuueeeeuuuueeeepppp))));;;;
  18.  
  19. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  20.      _S_L_G_e_t_Q_u_e_u_e returns a list of the jobs on the queue for the specified
  21.      printer. The function uses the current default spooling system.
  22.  
  23.      The _p_r_i_n_t_e_r__i_n_f_o parameter specifies the printer whose queue is to be
  24.      reported. Note that this parameter is a  pointer to an _S_L_P_r_i_n_t_e_r_S_t_r_u_c_t
  25.      structure and not a printer name. This is because _S_L_G_e_t_Q_u_e_u_e requires
  26.      information available in the structure to properly locate and read the
  27.      printer queue. A NNNNUUUULLLLLLLL _p_r_i_n_t_e_r__i_n_f_o parameter is illegal and will return
  28.      an error. Values for this parameter can be obtained directly from the
  29.      printer list returned by the _S_L_G_e_t_P_r_i_n_t_e_r_L_i_s_t(_3) function.
  30.  
  31.      _q_u_e_u_e__t_y_p_e specifies the type of queue to obtain. The value of this
  32.      parameter is used only for networked printers under the System V spooler.
  33.      Under the System V Release 3 spooling system there are two queues for a
  34.      networked printer, the queue on the local machine and the queue on the
  35.      remote machine. _q_u_e_u_e__t_y_p_e specifies which of these two queues should be
  36.      read and provides the capability to merge the two queues into one list.
  37.      The possible values for _q_u_e_u_e__t_y_p_e are:
  38.  
  39.      SSSSLLLL____QQQQUUUUEEEEUUUUEEEE____LLLLOOOOCCCCAAAALLLL      Obtain the network printer queue on the local
  40.                          machine.
  41.  
  42.      SSSSLLLL____QQQQUUUUEEEEUUUUEEEE____RRRREEEEMMMMOOOOTTTTEEEE     Obtain the network printer queue on the remote host
  43.                          machine.
  44.  
  45.      SSSSLLLL____QQQQUUUUEEEEUUUUEEEE____MMMMEEEERRRRGGGGEEEEDDDD     Merge the local and remote printer queues into one
  46.                          list. If a print job appears in both the local and
  47.                          remote printer queues, only the local job will be
  48.                          listed.
  49.  
  50.      _q_u_e_u_e_p is set by the function to point to a list of _S_L_Q_u_e_u_e_S_t_r_u_c_t
  51.      structures. These structures contain detailed information about each job
  52.      in the printer queue.  _n_u_m__q_u_e_u_e_p is set to the number of jobs in the
  53.      queue list.
  54.  
  55.      The _S_L_Q_u_e_u_e_S_t_r_u_c_t is defined as:
  56.  
  57.           typedef struct _slQueueStruct {
  58.               char *job_id;              /* Job ID                   */
  59.               char *username;            /* Job owner's user name    */
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSLLLLGGGGeeeettttQQQQuuuueeeeuuuueeee((((3333))))                    IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                     SSSSLLLLGGGGeeeettttQQQQuuuueeeeuuuueeee((((3333))))
  71.  
  72.  
  73.  
  74.               char *title;               /* Print job title, or name */
  75.                                          /* of first file in request */
  76.               unsigned int size;         /* Size of the job in bytes */
  77.               unsigned int is_local: 1;  /* 1 == job is in the local */
  78.                                          /*      queue (Sys V only)  */
  79.               unsigned int _padding: 31; /* Unused - for alignment   */
  80.               time_t time_stamp;         /* Submittal time           */
  81.           } SLQueueStruct;
  82.  
  83.  
  84. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  85.      0 is returned if execution was successful. -1 is returned and _S_L_e_r_r_n_o is
  86.      set if an execution error has occurred.
  87.  
  88. EEEEXXXXEEEECCCCUUUUTTTTIIIIOOOONNNN EEEERRRRRRRROOOORRRR CCCCOOOODDDDEEEESSSS
  89.      _S_L_G_e_t_Q_u_e_u_e will fail under the following circumstances.
  90.  
  91.      SL_ERR_FIND_SPOOLER      An error occurred while attempting to determine
  92.                               the available printer spooling systems.
  93.  
  94.      SL_ERR_NO_SPOOLERS       There are no printer spooling systems available.
  95.  
  96.  
  97.      SL_ERR_SPOOLER_ERROR     A printer spooling system error has occurred.
  98.  
  99.      SL_ERR_BAD_PRINTER_STRUCT
  100.                               An invalid printer structure has been specified.
  101.  
  102.  
  103.      SL_ERR_REMOTE            An error has occurred while attempting a remote
  104.                               shell execution (rsh). This error could be
  105.                               caused by transitory network problems. The
  106.                               function call should be retried.
  107.  
  108. WWWWAAAARRRRNNNNIIIINNNNGGGG
  109.      A pointer to _q_u_e_u_e_p obtained by a previous call to _S_L_G_e_t_Q_u_e_u_e will be
  110.      invalid after subsequent calls to the function. The contents of the queue
  111.      list _q_u_e_u_e_p must be copied to be preserved. Note that the character
  112.      string fields of the structure must be duplicated in any copy operation
  113.      since these pointers also become invalid.
  114.  
  115. NNNNOOOOTTTTEEEESSSS
  116.      All mention of "fields" refers to the fields of the _S_L_Q_u_e_u_e_S_t_r_u_c_t
  117.      structure.
  118.  
  119.      1.   Under the  BSD spooling system the _t_i_m_e__s_t_a_m_p field will be set to
  120.           the 0.
  121.  
  122.      2.   The _q_u_e_u_e__t_y_p_e parameter is only used by the System V spooling
  123.           system when a networked printer is specified. In all other cases the
  124.           value of this parameter is ignored.
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSLLLLGGGGeeeettttQQQQuuuueeeeuuuueeee((((3333))))                    IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo                     SSSSLLLLGGGGeeeettttQQQQuuuueeeeuuuueeee((((3333))))
  137.  
  138.  
  139.  
  140.      3.   The _t_i_m_e__s_t_a_m_p field contains the value returned by the time(2)
  141.           function. Refer to the time(2) and ctime(3) man pages for
  142.           information about the time value and how it may be converted to a
  143.           time string.
  144.  
  145.      4.   Under System V spooling _S_L_G_e_t_Q_u_e_u_e must perform network command
  146.           execution to obtain queue information for a remote printer. If a
  147.           connection to the remote machine cannot be established _S_L_G_e_t_Q_u_e_u_e
  148.           will return an error indication and set _S_L_e_r_r_n_o to SSSSLLLL____EEEERRRRRRRR____RRRREEEEMMMMOOOOTTTTEEEE.
  149.           Upon receiving this error, an application should retry the call a
  150.           number of times to ensure that the failure is not due to a
  151.           transitory network problem.
  152.  
  153.      5.   Under System V spooling _S_L_G_e_t_Q_u_e_u_e must perform network command
  154.           execution to obtain queue information for a remote printer. Remote
  155.           command execution is attempted as the user 'lp'. Normally, the lp
  156.           account will not have a passwd and access is freely granted. If an
  157.           installation protects the lp account with a password and uses the
  158.           rhosts mechanism, _S_L_G_e_t_Q_u_e_u_e will fail to get permission to access
  159.           the remote queue.  An example of how an application might handle
  160.           this situation is to run as a setuid lp program and bracket its
  161.           calls to _S_L_G_e_t_Q_e_u_e_u_e with the _s_e_t_r_e_u_i_d(_2) and _s_e_t_r_e_g_i_d(_2) functions.
  162.           For example, assume that the following code is executed by a program
  163.           that has uid=joe and euid=lp.
  164.  
  165.  
  166.  
  167.           /* Swap uid with euid and gid with egid.
  168.              Thus uid=lp and euid=joe
  169.            */
  170.           setreuid(geteuid(), getuid());
  171.           setregid(getegid(), getgid());
  172.  
  173.           /* Get the remote queue as lp */
  174.           SLGetQueue(prptr, queue_type, &queue, &numjobs);
  175.  
  176.           /* Swap everything back. Thus uid=joe and euid=lp */
  177.           setreuid(geteuid(), getuid());
  178.           setregid(getegid(), getgid());
  179.  
  180.  
  181.      6.   The _t_i_t_l_e field will be NNNNUUUULLLLLLLL if _l_i_b_s_p_o_o_l was unable to determine the
  182.           title of a print job.
  183.  
  184. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  185.      SLGetPrinterList(3), SLSubmitJob(3), SLPerror(3), libspool(3) time(2),
  186.      ctime(3), setreuid(2), setregid(2)
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.